Scripting
Documentation
Changelog
Privacy
Documentation
Changelog
Privacy

Writing Health Category Samples PRO

Requires Scripting PRO

The Scripting app allows you to write categorical health data to Apple HealthKit using the HealthCategorySample class and the Health.saveCategorySample() method. Category samples represent discrete health-related events or conditions, such as sleep stages, mindful sessions, menstrual flow, ovulation test results, and more.

This guide describes how to create and save a HealthCategorySample.

Prerequisites

  • Confirm that HealthKit is available on the device:

    1if (!Health.isHealthDataAvailable) {
2  throw new Error("Health data is not available on this device.")
3}

  • Ensure the script has the required permission for the target category type. The Scripting app will automatically request authorization if needed when saving.

1. Create a HealthCategorySample

Use HealthCategorySample.create() to construct a new category sample.

Parameters

  • type: A HealthCategoryType string (e.g., "sleepAnalysis", "mindfulSession", "menstrualFlow", etc.).
  • startDate: The beginning of the time interval that the event applies to (JavaScript Date).
  • endDate: The end of the event’s time interval (JavaScript Date).
  • value: The integer value representing the state of the category. You must use the corresponding enum value based on the type.
  • metadata (optional): An optional metadata object describing additional attributes.

Value Mapping

The value must be one of the pre-defined category values. For example:

  • For "sleepAnalysis", use the HealthCategoryValueSleepAnalysis enum:

    • HealthCategoryValueSleepAnalysis.asleepCore
    • HealthCategoryValueSleepAnalysis.awake
    • etc.

  • For "menstrualFlow", use HealthCategoryValueSeverity:

    • HealthCategoryValueSeverity.mild, moderate, severe, etc.

Refer to each category type’s enum definition for valid values.

Example

1const sample = HealthCategorySample.create({
2  type: "sleepAnalysis",
3  startDate: new Date("2025-07-03T23:00:00"),
4  endDate: new Date("2025-07-04T07:00:00"),
5  value: HealthCategoryValueSleepAnalysis.asleepCore,
6  metadata: {
7    source: "ScriptingApp"
8  }
9})
10
11if (!sample) {
12  throw new Error("Failed to create HealthCategorySample.")
13}

2. Save the Category Sample

Use Health.saveCategorySample() to save the created sample to HealthKit.

1await Health.saveCategorySample(sample)

If saving fails (e.g., due to permission denial), the promise will reject with an error.

Full Example

1async function writeSleepData() {
2  const sample = HealthCategorySample.create({
3    type: "sleepAnalysis",
4    startDate: new Date("2025-07-03T23:00:00"),
5    endDate: new Date("2025-07-04T07:00:00"),
6    value: HealthCategoryValueSleepAnalysis.asleepCore,
7  })
8
9  if (!sample) {
10    console.error("Failed to create sample.")
11    return
12  }
13
14  try {
15    await Health.saveCategorySample(sample)
16    console.log("Sleep data saved successfully.")
17  } catch (err) {
18    console.error("Error saving sample:", err)
19  }
20}
21
22writeSleepData()

Notes

  • The value must be a valid enum for the selected type, or the creation will fail.
  • startDate and endDate define the time range the event applies to — e.g., a sleep session or a mindful moment.
  • Metadata is optional but can be useful for tagging data source or context.
Outline